v5.36.2

Compare Source

Fixed

• Field: Export FieldItem component from the top-level package. The component was previously only accessible via
  the Field.Item namespace.

• DownloadTrigger: Extract the download logic into a useDownload hook. The DownloadTrigger component now simply
  consumes this hook, making the browser-download behavior reusable outside of the trigger component.

v5.36.1

Compare Source

Fixed

• Popover: Add finalFocusEl and restoreFocus props to control focus behavior when the popover closes.
  finalFocusEl lets you specify an element to receive focus instead of the trigger, and restoreFocus (default
  true) controls whether focus returns to the trigger at all.

<Popover.Root finalFocusEl={() => myInputRef} restoreFocus={false}>
  ...
</Popover.Root>

• Color Picker: Fix color value to respect the specified format when setting values via props or setValue.
  Previously, the internal color object could retain a mismatched format (e.g., RGB when format is hsla), causing
  inconsistent value objects in onValueChange callbacks.

• Date Input: Fix min/max constraints resetting other segments mid-keystroke. Validation now defers until the
  segment is fully typed or on blur.

• Date Picker: Fix onValueChange not firing when only time segments change in CalendarDateTime or
  ZonedDateTime values.

• Navigation Menu: Remove aggressive and redundant default aria-label.

v5.36.0

Compare Source

Added

• Add new DateInput component for typing dates with keyboard input.

<DateInput.Root>
  <DateInput.Label />
  <DateInput.Control>
    <DateInput.SegmentGroup>
      <DateInput.Segment />
    </DateInput.SegmentGroup>
  </DateInput.Control>
  <DateInput.HiddenInput />
</DateInput.Root>

• Multiple Trigger Support: No more duplicating a Dialog for every button in a list — render one instance and share
  it across as many triggers as you need. Each trigger gets a value, and the component repositions automatically when
  switching between them.

  <Dialog.Root>
    <Dialog.Trigger value="user-1">Edit Alice</Dialog.Trigger>
    <Dialog.Trigger value="user-2">Edit Bob</Dialog.Trigger>
    {/* one dialog, reused for both */}
  </Dialog.Root>

  Supported in Dialog, Drawer, Hover Card, Menu, Popover, and Tooltip.

• Splitter: Nest splitters to build grid-like layouts. When a horizontal and vertical splitter meet at an
  intersection, you can drag both directions at once. Use createRegistry() to connect the splitter instances.

  const registry = Splitter.createRegistry()
  
  <Splitter.Root orientation="horizontal" registry={registry}>
    <Splitter.Panel>
      <Splitter.Root orientation="vertical" registry={registry}>
        ...
      </Splitter.Root>
    </Splitter.Panel>
  </Splitter.Root>

• Tags Input: Add sanitizeValue prop to clean up tag values before they're added — trim whitespace, lowercase,
  strip special characters, whatever you need. Defaults to (v) => v.trim().

  <TagsInput.Root sanitizeValue={(v) => v.trim().toLowerCase()} />

• Toast: Add priority-based queuing. When you've hit the max visible toasts, incoming ones are queued and sorted so
  the most important ones show first.

• Floating Panel: Add initialFocusEl, finalFocusEl, and restoreFocus props to control which element gets focus
  when the panel opens or closes.

Fixed

• Date Input: Fix crash where event.nativeEvent.isComposing is undefined. The composing check now uses a
  framework-agnostic utility that works across all adapters.

• Dialog / Drawer: Avoid setting inline pointer-events when modal, letting the dismissable layer manage it
  instead.

• File Upload: Automatically reject duplicate files with FILE_EXISTS error. Previously, uploading the same file
  twice was silently accepted and deleting one duplicate removed all of them.

• Splitter: Fix onResizeStart and onResizeEnd callbacks to fire for programmatic resizes.

• Tags Input: Set enterKeyHint to "done" on the input element so mobile virtual keyboards show a "Done" button
  that triggers tag addition.

• Toast: Restore role="region" on the toast group element. The role was previously removed to reduce screen reader
  landmark noise, but this caused an axe aria-prohibited-attr violation since aria-label is not permitted on a div
  without a valid role.

• Tour: Fix step navigation events (next, prev, setStep) firing when the tour is inactive, bypassing the
  start flow. Fix popper styles not being cleaned up when transitioning from a tooltip step to a dialog step.

• Tree View: Add data-checked and data-indeterminate attributes to item and branch control elements for styling
  based on checked state.

• Accordion: Fix missing data-focus attribute on getItemTriggerProps.

• Combobox: Fix VoiceOver not announcing combobox options when navigating with arrow keys. Safari/VoiceOver ignores
  aria-activedescendant changes on combobox inputs, so a live region is now used to announce the highlighted item on
  Apple devices.

• Menu: Fix issue where quick diagonal pointer movement toward an open submenu could flash the highlight across
  sibling items you skim past.

v5.35.0

Compare Source

Added

• Date Picker: Improved range picker mode with new data attributes and state properties.

  • Added missing range data attributes (data-range-start, data-range-end, data-in-hover-range,
    data-hover-range-start, data-hover-range-end) to month and year cell triggers.
  • TableCellState now includes firstInRange, lastInRange, inHoveredRange, firstInHoveredRange,
    lastInHoveredRange, and outsideRange.
  • Range boundary dates now announce "Starting range from {date}" and "Range ending at {date}" for better screen reader
    context.
  • Fixed inverted year cell selectable state that caused years outside the visible decade or min/max range to appear
    selectable.
  • Breaking: DayTableCellState.formattedDate removed — use valueText instead (inherited from TableCellState).

• Drawer: Added new anatomy parts and improved swipe gestures.

  • Added description anatomy part with aria-describedby support on the content element.
  • Added SwipeArea part for swipe-to-open gestures from screen edges.
  • Require intentional swipe movement before showing the drawer (no flash on pointer down).
  • Smooth settle animation from release point to fully open position.
  • Added cross-axis scroll preservation to prevent drawer drag when scrolling horizontally.
  • Added initial focus management for non-modal mode.
  • Set pointer-events: none on positioner in non-modal mode so the page stays interactive.
  • Fixed swipe-to-dismiss in controlled mode (open: true without onOpenChange now blocks dismiss).

• Field: Added Field.Item component and target prop on Field.Root for multi-control fields (e.g., currency
  select + amount input). Use Field.Item with a value to scope controls, and target to specify which item the
  label should focus when clicked.

• Interaction: Added useInteractionModality and useFocusVisible hooks for tracking user input method (keyboard,
  pointer, virtual) and conditionally showing focus rings.

• Listbox: Added keyboardPriority to input props to control whether key handling prioritizes text editing or list
  navigation for Home/End and horizontal arrows in grid collections. Added highlightFirst, highlightLast,
  highlightNext, and highlightPrevious to the API for programmatic highlight navigation.

• Pin Input: Overhauled deletion, focus management, and added new props.

  • Delete and Backspace now splice values left instead of leaving empty gaps. Deleting "2" from [1, 2, 3] yields
    [1, 3, ""] — not [1, "", 3].
  • Smarter focus management: Backspace always moves back, click and ArrowRight are clamped to the insertion point,
    same-key skip advances focus, and roving tabIndex treats the entire pin input as a single tab stop.
  • Added Home/End to jump to first slot or last filled slot.
  • Added enterKeyHint showing "next" on intermediate slots and "done" on the last.
  • Added autoSubmit prop to automatically submit the owning form when all inputs are filled.
  • Added sanitizeValue prop to sanitize pasted values before validation (e.g. strip dashes from "1-2-3").

• Tags Input: Added allowDuplicates prop to allow duplicate tags.

• Clipboard, Navigation Menu, Popover, Select, Timer, Tree View: Added translations prop for localizing hardcoded
  accessibility labels.

Fixed

• Carousel: Fixed controlled carousel inside dialog jumping or skipping pages. Fixed navigation inside
  CSS-transformed containers (e.g., dialogs with open/close animations). Fixed scroll position drifting when container
  layout shifts (e.g., scrollbar removal).

• Color Picker: Fixed vertical slider orientation not preserved on pointer updates.

• Date Input: Improved focus management.

• Dialog: Improved non-modal mode behavior.

  • Set pointer-events: none on positioner in non-modal mode so the page stays interactive.
  • Added initial focus management for non-modal mode (mirrors popover behavior).
  • Fixed aria-modal to reflect actual modal prop value instead of hardcoded true.

• Floating Panel: Fixed open taking precedence over defaultOpen during initialization. Fixed setPosition and
  setSize to work independently of drag/resize state. Fixed maximize/minimize restore reverting to (0, 0) in
  controlled mode. Fixed Maximum update depth exceeded when content uses ResizeObserver (React). Fixed Escape during
  drag/resize to cancel and revert to original position/size.

• Focus Trap: Fixed edge cases in focus trapping.

  • Fixed focus trapping when the content has a single effective tab stop, such as a native radio group.
  • Handle disconnected initialFocus nodes more safely.

• Interact Outside: Fixed Safari-specific interaction issue.

  • Fixed issue where nested popovers and select within popovers didn't toggle correctly in Safari due to focusin
    events racing with pointer interactions.

• Menu: Fixed trigger to keep aria-expanded="false" when closed.

• Pin Input: Fixed crash when typing the same character in a completed pin input.

• Radio Group, Tabs: Fixed indicator only animating on value change, not on initial render or resize.

• Splitter: Fixed shadow root compatibility.

  • Fixed global cursor styles when splitter is used in a shadow root.

v5.34.1

Compare Source

Fixed

• Carousel:
  • Fixed issue where carousel inside a Portal (e.g., Dialog) computes incorrect page count due to incomplete DOM layout
    at mount time
  • Keep page and indicators in sync after drag release and scroll settling
  • Handle rapid mixed interactions (drag, wheel, buttons, indicators) more consistently
  • Keep page state valid when slidesPerPage, slidesPerMove, direction, or orientation change
  • Make slidesPerMove progression more predictable
• Combobox, Listbox, Select: Improved controlled-mode synchronization and callback/item resolution behavior across
  collections
• Menu: Fixed MenuCheckboxItem to use getOptionItemState for optionItemState context lookup

Changed

• Format: Format.Time now accepts amLabel and pmLabel as separate props instead of the previous amPmLabels
  object

v5.34.0

Compare Source

Added

• Format: Added Format.Time for formatting time values and examples for basic, date input, seconds, custom AM/PM
  labels, and locale

Fixed

• Build: Fixed CJS build issues in downstream Zag.js packages

v5.33.0

Compare Source

Added

• Date Picker: Added non-Gregorian calendar support via createCalendar prop (Persian, Buddhist, Islamic, Hebrew,
  and other calendar systems)

  import { PersianCalendar } from '@​internationalized/date'
  
  function createCalendar(identifier) {
    switch (identifier) {
      case 'persian':
        return new PersianCalendar()
      default:
        throw new Error(`Unsupported calendar: ${identifier}`)
    }
  }
  
  ;<DatePicker.Root locale="fa-IR" createCalendar={createCalendar}>
    {/* ... */}
  </DatePicker.Root>

• Date Picker: Added data-type attribute to weekend table header and cell

Fixed

• Combobox: Fixed onValueChange returning empty items array when using controlled value
• Popover: Fixed nested popover z-index layering
• Toast: Fixed types to ensure parent/index are exposed as props and expand/collapse are exposed on the
  store
• Radio Group, Listbox, Progress, Segment Group: Fixed group labels rendering orphan label elements; now render as
  span per W3C ARIA pattern

v5.32.0

Compare Source

Added

• Locale: Added useDateFormatter hook for localized date formatting using @internationalized/date
• Swap: Added new Swap component for toggling between two visual states with CSS animations using dual presence
  instances
• Checkbox: Added maxSelectedValues prop to CheckboxGroup to limit the number of selected values
• Drawer: Replaced BottomSheet with new Drawer component supporting multi-directional swipe via swipeDirection
  prop (up, down, left, right), a new Positioner part, and snapToSequentialPoints option
• Date Picker:
  • Added focus option to api.clearValue({ focus?: boolean })
  • Added api.setTime(time, index?) for date-time picker support
  • Added maxSelectedDates prop to limit selected dates in multiple selection mode
  • Added api.isMaxSelected to check if maximum number of dates has been selected
  • Added openOnClick prop to open the calendar when clicking the input field
  • Added showWeekNumbers support to display ISO 8601 week number column in the day view
• Popover: Added sizeMiddleware positioning option to optionally disable the size middleware
• Select: Added autoComplete prop for browser autofill hints

Fixed

• Combobox:
  • Fixed aria-selected being set on highlighted items instead of selected items
  • Fixed selectedItems getting out of sync with value in controlled mode
  • Fixed item disabled state not accounting for root-level disabled prop
• Date Picker:
  • Fixed api.selectToday() sending incorrect value format
  • Preserve time/timezone when selecting new dates (CalendarDateTime and ZonedDateTime)
  • Improved focus management in trigger-only mode
• Dialog: Fixed non-modal dialog closing on outside click when modal is false
• Listbox: Fixed DOM IDs
• Number Input: Fixed invalid prop being ignored when value is out of range
• Popover: Improved performance by reducing style recalculations when scrolling
• Select: Fixed autofill not updating value when hidden select value changes

v5.31.0

Compare Source

Added

• Date Picker: Added ValueText component for displaying selected date value(s) with placeholder support and render
  prop for custom formatting
• Scroll Area: Added overflow CSS variables (--scroll-area-overflow-{x,y}-{start,end}) for scroll fade effects
• Slider: Added thumbCollisionBehavior prop (none, push, swap)
• Steps: Added isStepValid, isStepSkippable, and onStepInvalid for validation support
• Tags Input: Added placeholder prop (shown only when no tags exist)
• Tooltip: Added data-instant attribute for instant animations

Fixed

• Auto Resize: Fixed change event not emitted after clearing controlled textarea
• Date Picker: Fixed visibleRangeText to show correct format based on current view (year/month/day)
• Dismissable: Fixed issue where closing a nested dialog/popover would incorrectly close its parent layers
• Menu: Fixed glitchy submenu behavior when hovering between trigger items quickly
• SSR: Fixed Deno SSR crashes by replacing native HTML elements with ark factory components
• Checkbox: Fixed individual checkbox props being overridden by CheckboxGroup
• Collection, Tree View: Fixed initial focus when first node/branch is disabled
• Color Picker: Fixed color not updating when selecting black shades in controlled mode
• Floating Panel: Fixed double-click on minimized title bar incorrectly maximizing
• Image Cropper: Fixed reset() destroying cropper, prop changes not updating instantly, and panning bounds
• Number Input: Fixed cursor positioning after clicking label or scrubbing
• Pagination: Fixed next trigger not disabled when count is 0
• Slider: Fixed thumb drag from edge in thumbAlignment="contain" mode
• Switch: Fixed api.toggleChecked() not working
• Toast: Fixed toasts created before state machine connects not showing
• Tour: Fixed janky scroll between steps

v5.30.0

Compare Source

Added

• Date Picker: Added required and invalid props
• Number Input: Added onValueCommit callback that fires when the input loses focus or Enter is pressed
• Pagination:
  • Added FirstTrigger and LastTrigger components for navigating to first/last page
  • Added boundaryCount parameter for controlling boundary pages (start/end)
  • Implemented balanced pagination algorithm for consistent UI with max 7 elements
• Radio Group: Added invalid and required props with corresponding data-* and aria-* attributes
• Tree View: Added scrollToIndexFn prop to enable keyboard navigation in virtualized trees

Fixed

• Accordion, Menu: Fixed issue where querying elements by aria-controls attribute could fail when lazy mounting
  the content
• Color Picker: Added role="dialog" to content and aria-haspopup="dialog" to trigger when not inline for better
  accessibility
• Date Picker: Fixed issue where date picker input does not update format when locale changes
• Floating Panel:
  • Fixed dir prop now properly delegated to all panel parts
  • Fixed double-click behavior improvements and to check event.defaultPrevented for custom behavior
• Listbox:
  • Fixed issue where data-highlighted wasn't applied to the first item when using autoHighlight with input
    filtering
• Number Input:
  • Fixed improved controlled usage sync
  • Fixed issue where input element doesn't sync when formatOptions changes dynamically
  • Ensured cursor position is preserved when Enter key is pressed and formatting is triggered
  • Fixed cursor jumping to start when value is changed externally via props while user is typing
• Pagination: Fixed ellipsis showing when only 1 page gap
• Rating Group: Fixed issue where rating group becomes unfocusable via keyboard when value is 0
• Tooltip: Fixed tooltip not showing when scrolling with pointer over trigger

Changed

• Tree View: getVisibleNodes() now returns { node, indexPath }[] instead of node[]

v5.29.1

Compare Source

Fixed

• Fieldset: Fixed aria-describedby resolution to correctly reference helper text and error text IDs
• Floating Panel:
  • Fixed resize trigger issue with n axis by explicitly setting top: 0
  • Fixed draggable and resizable options not being respected when set to false
• Presence: Fixed regression where UNMOUNT transition might not be called consistently

v5.29.0

Compare Source

Added

• Carousel, Color Picker, Combobox, Date Picker, Select: Added value to OpenChangeDetails for better context
  when handling open state changes
• Carousel: Added support for autoSize prop to allow variable width/height slide items
• Splitter:
  • Added Splitter.ResizeTriggerIndicator to render an indicator when resizing
  • Exported getLayout and getSplitterLayout functions for calculating splitter panel layouts
• Toast: Exposed viewport offset as CSS variables on the toast group element

Fixed

• Carousel:
  • Fixed dragging behavior that stops working after switching browser tabs or scrolling the page
  • Fixed dragging not working after scrolling with mouse wheel when allowMouseDrag is enabled
• Combobox: Fixed onHighlightChange not being invoked when collection is filtered to empty
• Date Picker: Fixed issue where the range date picker crashes when typing the end date first and blurring the input
  field multiple times
• File Upload: Fixed issue where clicking on non-interactive children inside the dropzone doesn't open the file
  picker
• Presence: Fixed a bug where elements get stuck in unmountSuspended state during rapid state updates
• Radio Group:
  • Fixed inconsistent application of data-focus-visible and data-focus attributes
• ScrollArea: Removed unnecessary createMemo wrapper in scrollbar props as is already reactive.
• Splitter: Fixed disabled splitter showing resize cursor and allowing dragging
• Tabs:
  • Fixed tabs indicator position not updating when inactive tabs change size
• Tags Input: Fixed issue where item delete trigger doesn't have data-* attached

v5.28.0

Compare Source

Added

• General: Exported InteractOutsideEvent, FocusOutsideEvent, and PointerDownOutsideEvent types for better type
  safety
• Carousel:
  • Added Carousel.AutoplayIndicator component for conditionally rendering content based on autoplay state
  • Added Carousel.ProgressText component for displaying current page progress (e.g., "1 / 5")
• Toast: Exported ToastOptions and ToastStoreProps types for better type safety

Changed

• useListCollection: Updated initialItems to accept readonly arrays for better compatibility with immutable data
  patterns.
• CollectionItem: Use the collection type from @zag-js/collection just like the other frameworks.

Fixed

• Combobox:
  • Fixed focus stealing in controlled open mode
  • Removed problematic aria-hidden behavior to allow interaction with other page elements